Network Micro-Code Engine

01. Executive decision

This is a separate execution domain, not a second emulator. Every connected participant still views and controls one authoritative host machine. Spectators receive the same display without acquiring input privileges.

Why: machine-specific network logic otherwise migrates into hard-coded branches; conversely, interpreting each packet or pixel through micro-code would recreate the dispatch bottleneck already identified elsewhere in PHLEGM. NMCE provides a policy layer while leaving the hot path native.

02. Existing PHLEGM v10 baseline

The proposed work builds on PHLEGM v10 r2, the first LAN shared-session line. That source includes a host-authoritative input/display bridge, machine-owned network-input.config.phlegm exposure profiles, a viewer and host administration UI, and a PowerShell 7/.NET relay replacing the r1 Python prototype.

These are source-level baseline descriptions, not new functionality delivered by this Dev-Note. The architecture proposed below does not imply that r3 already exists.

03. Responsibility boundaries

04. Execution architecture

The emulator and relay remain independently scheduled. The relay may go offline without halting hardware execution. NMCE may initialize and accept authenticated participants before a machine is booted; a machine change revokes controller assignments and forces profile reevaluation.

05. Micro-code execution domains

Extend the existing compiler to produce instruction programs tagged by domain. Network instructions execute in a dedicated context, not by injecting opcodes into CPU/PPU/APU streams.

Use the existing compiler infrastructure and compatible typed intermediate representation where practical. The network VM has its own verified opcode whitelist, numeric limits, stack/register allocation, and execution budgets.

06. Proposed NET instruction set

These are design names, not opcodes presently recognized by PHLEGM. Their concrete signatures and bytecode values should be registered by a versioned network instruction catalog.

Each instruction returns a bounded typed result; failures produce typed error codes and are logged without crashing the emulated machine. Avoid generic NET_EXEC, unrestricted pointers, arbitrary filesystem I/O, and any “host command” escape hatch.

07. Definition ownership and example schema

Maintain two separate kinds of machine-readable definitions:

1. Machine-owned input definitions describe real controller ports, keyboard matrices, optional multitaps, and their emulated electrical behavior; existing cfg/machine/<vendor>/<machine>/network-input.config.phlegm describes what the network is allowed to expose.
2. Global NMCE definitions declare network instruction programs, session state-machine transitions, assignment policies, and transport capabilities. They may reference exposed machine ports but must not redefine machine hardware.

Illustrative proposed location: cfg/network/microcode/network-session.config.phlegm.

# EXAMPLE ONLY — proposed NMCE schema, NOT a currently supported parser contract.
[network.engine]
domain=network
schema=1
execution=event-driven
max_instructions_per_event=256
max_pending_events=1024

[network.session]
model=authoritative-host
default_role=spectator
controller_assignment=host-approved
on_machine_change=revoke-all-assignments

[network.input]
source=normalized-virtual-device
stale_input_timeout_ms=750
shared.digital_merge=or-neutralize-opposites
shared.analog_merge=owner-priority

[network.stream]
video.source=completed-native-framebuffer
video.delivery=native-worker
audio.source=completed-mixed-audio
audio.delivery=native-worker

[network.program.user_join]
when=authenticated-user-joined
steps=NET_USER_JOIN,NET_PERMISSION_CHECK

[network.program.input]
when=validated-input-event
steps=NET_INPUT_VALIDATE,NET_PERMISSION_CHECK,NET_INPUT_MERGE,NET_INPUT_APPLY

The concrete grammar must be reconciled with PHLEGM's existing parser. Configuration values such as the queue depth and instruction budget above are example limits, not measured performance targets or fixed implementation values.

08. Input timing, arbitration and disconnection

Input flow

remote HID / keyboard
  → authenticated, parsed native event
  → per-client rate/size limits
  → NMCE: validate → authorize → assign/merge policy
  → immutable normalized virtual-device snapshot
  → emulation-thread input boundary
  → machine-specific hardware micro-code
  → CPU sees ordinary controller/keyboard behavior

The emulation thread performs a nonblocking read of the most recent authorized snapshot at existing input sample boundaries. It does not wait for a client, packet retransmission, or NMCE job. New input arriving after a sample boundary applies at the next legal boundary.

Conflicting controls

For shared digital buttons, default to logical OR. For opposite directions, neutralize both directions unless the selected machine profile requires a more specific policy. For analog axes, use an explicitly declared owner-priority, last-valid-event, or neutral policy; never sum arbitrary remote values without bounds.

On client disconnect, permission revoke, machine switch, missed heartbeat, or session closure, atomically publish a released/neutral state for every affected device. Maintain monotonic sequence IDs and assignment generations so late packets cannot revive a removed controller.

Network activity must not alter the emulated input hardware's timing or map a client's raw keycodes directly onto emulated memory.

09. Shared display and audio for every participant

Viewer output is independent of controller assignments: removing a user's controller may leave them as a spectator. Disabling video/audio permissions affects their subscription, not another participant's stream.

Preserve native aspect ratio, scan/frame ordering, and pixel scaling options. Put encoding and transport behind bounded queues. If a viewer falls behind, discard obsolete display frames or downgrade stream quality rather than blocking the emulation thread. Audio uses timestamps and a jitter buffer as appropriate; it should not be “fixed” by changing emulated APU clock rates.

In early revisions, continue using the existing PNS1 PNG bridge until an independently verified media path replaces it. Remote audio and secure internet delivery remain future implementation items—their inclusion in the proposed instruction catalog is not a claim they currently work.

10. Scheduling and performance invariants

• Event-driven: sleep when there is no network work; no high-frequency interpreter loop for idle sockets.
• Separate state: NMCE context contains only session metadata, handles, deadline counters, and authorized device states.
• Bounded: finite event queue depth, maximum per-event instruction count, per-peer input-rate limits, maximum client count, and bounded media backlog.
• Nonblocking: no network lock, socket, relay process, or encoder can stall CPU/PPU/APU execution.
• Fast path: micro-code governs control transitions; common streaming and input-copy operations use native routines.
• Observable: record events/s, control-VM time, queue occupancy, dropped frames, client RTT, unauthorized packets, and controller release latency.
• Fail-safe: if NMCE or relay fails, clear all remote inputs and continue local emulation.

Prefer reuse of existing compiled instruction representations where it saves maintenance effort, but do not force all network transitions through the general CPU opcode dispatch path if it causes measurable hot-loop overhead. A dedicated validated dispatch table or compiled event handler is appropriate.

11. Trust, permissions and security model

The boundary begins before network micro-code execution. Native transport authenticates and parses packets into typed events. The NMCE then evaluates host-owned session policy and produces only allowed intents.

The current v10 r2 HTTP relay is strictly a trusted-LAN prototype. Do not describe it as encrypted or internet-safe. For remote internet support, add audited encryption/authenticated signaling and suitable NAT traversal in the native transport layer before lifting LAN restrictions.

12. Compiler, cache and architecture rules

Integrate NMCE compilation into the existing PHLEGM compiler as a separate definition component. Cache its compiled output by source dependency/content fingerprint, network opcode ABI, schema version, and compiler version. A change to a network policy should not unnecessarily invalidate unrelated CPU, PPU, or APU compiled components.

Preserve existing per-project/per-version incremental-build accounting. A network component without a known successful compile duration is compiled, not automatically reused. Track the duration when it successfully compiles and skip only on verified cache matches.

Required architectural restrictions: no Python in build/runtime; do not relax Validate-BuildArchitecture.ps1; retain the PowerShell 7/.NET native relay approach until a verified replacement exists; ensure shared compiler GUI behavior remains consistent with Mindrealm where that GUI is common. Network source belongs to PHLEGM and should not force Mindrealm to load NMCE unless specifically requested.

Recommended build output: a typed and versioned network-microcode image, diagnostics listing accepted instructions and missing definitions, and a deterministic compatibility error if the runtime does not support the compiled network ABI.

13. Suggested implementation phases

Version proposal: start the policy-engine foundation in PHLEGM v10 r3, but increment the revision only when an actual, tested source revision is produced. This document alone does not create r3.

14. Acceptance tests

1. Single source of truth: two remote controllers and a spectator observe and affect one host machine, not independently running copies.
2. Visibility: a spectator without controller permission receives the live display; a revoked controller may remain a viewer.
3. Input policy: exclusive assignment, shared digital OR, opposite-direction neutralization, analog ownership, and per-machine port limits behave as declared.
4. Timing: input becomes visible at supported emulated sampling boundaries; clock/device semantics are unchanged.
5. Safety: revoking or dropping a client releases held inputs even if stale packets arrive afterward.
6. Performance: slow network peers or encoders do not stall emulation; bounded queue overflows drop events/frames with diagnostic counters.
7. Cross-machine: PET keyboard, NES two-player, SNES controllers, and any definition-provided multitap ports use their native input hardware.
8. Isolation: network instruction verification rejects host I/O, memory writes, unauthorized commands, and invalid definition references.
9. Compiler: network-only definition edits invalidate only impacted compilation components; unknown prior durations cause a fresh compile.
10. Compatibility: Hosted Definitions, local input, normal monitor operation, existing graphics backends, and r2 LAN session paths continue operating.
11. Deployment: relay cannot accidentally enable public, unauthenticated HTTP access; WAN functionality requires explicit secure transport.
12. Verification honesty: separate static/unit tests, native build results, LAN end-to-end checks, and WAN checks in every release report.

Do not report a working integrated feature merely because configuration/schema tests pass. A Windows native build and at least one real host-plus-client run must be validated before declaring the feature complete.

15. Risks and open design decisions

16. Final decision record

Accepted design principles: one authoritative emulated machine; multiple controllers and spectators; shared video and (when implemented) audio for viewers; machine-owned physical hardware definitions; host-controlled security; dedicated network instruction domain; native socket/media path; fail-safe remote input release; nonblocking performance; independently cached compilation.

Explicitly excluded: interpreting each packet byte, rendered pixel, or audio sample with micro-code; introducing Python as a dependency; allowing network instructions to modify guest memory directly; and claiming proposed v10 r3 capabilities as already delivered.

Reference baseline: PHLEGM v10 r2 shared-session source and design notes. This Dev-Note is intended as a build specification for a future implementation, not a compiler patch or runtime release.